home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / catD / copyout.z / copyout
Encoding:
Text File  |  1998-10-30  |  8.3 KB  |  131 lines
  1.  
  2.  
  3.  
  4. ccccooooppppyyyyoooouuuutttt((((DDDD3333))))                                                        ccccooooppppyyyyoooouuuutttt((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _cccc_oooo_pppp_yyyy_oooo_uuuu_tttt - copy data from a driver buffer to a user buffer
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  14.      _iiii_nnnn_tttt _cccc_oooo_pppp_yyyy_oooo_uuuu_tttt_((((_cccc_aaaa_dddd_dddd_rrrr______tttt _d_r_i_v_e_r_b_u_f_,,,, _cccc_aaaa_dddd_dddd_rrrr______tttt _u_s_e_r_b_u_f_,,,, _ssss_iiii_zzzz_eeee______tttt _c_o_u_n_t_))))_;;;;
  15.  
  16.    AAAArrrrgggguuuummmmeeeennnnttttssss
  17.      _d_r_i_v_e_r_b_u_f Driver source address from which copy is made.
  18.  
  19.      _u_s_e_r_b_u_f   User destination address to which copy is made.
  20.  
  21.      _c_o_u_n_t     Number of bytes to copy.
  22.  
  23. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  24.      _cccc_oooo_pppp_yyyy_oooo_uuuu_tttt copies _c_o_u_n_t bytes of data from the kernel virtual address
  25.      specified by _d_r_i_v_e_r_b_u_f to the user virtual address specified by _u_s_e_r_b_u_f.
  26.  
  27.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  28.      On success, _cccc_oooo_pppp_yyyy_oooo_uuuu_tttt returns 0.  On failure, it returns -1 to indicate
  29.      that the specified user address range is not valid.
  30.  
  31. UUUUSSSSAAAAGGGGEEEE
  32.      _cccc_oooo_pppp_yyyy_oooo_uuuu_tttt chooses the best algorithm based on address alignment and number
  33.      of bytes to copy.  Although the source and destination addresses are not
  34.      required to be word aligned, word aligned addresses may result in a more
  35.      efficient copy.
  36.  
  37.      Drivers usually convert a return value of -1 into an _EEEE_FFFF_AAAA_UUUU_LLLL_TTTT error.
  38.  
  39.    LLLLeeeevvvveeeellll
  40.      Base only.
  41.  
  42.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  43.      Can sleep.
  44.  
  45.      Driver-defined basic locks and read/write locks may not be held across
  46.      calls to this function.
  47.  
  48.      Driver-defined sleep locks may be held across calls to this function.
  49.  
  50.    WWWWaaaarrrrnnnniiiinnnnggggssss
  51.      The driver source buffer must be completely within the kernel address
  52.      space, or the system can panic.
  53.  
  54.      When holding sleep locks across calls to this function, drivers must be
  55.      careful to avoid creating a deadlock.  During the data transfer, page
  56.      fault resolution might result in another I/O to the same device.  For
  57.      example, this could occur if the driver controls the disk drive used as
  58.      the swap device.
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. ccccooooppppyyyyoooouuuutttt((((DDDD3333))))                                                        ccccooooppppyyyyoooouuuutttt((((DDDD3333))))
  70.  
  71.  
  72.  
  73.    EEEExxxxaaaammmmpppplllleeeessss
  74.      A driver _iiii_oooo_cccc_tttt_llll(D2) routine (line 5) can be used to get or set device
  75.      attributes or registers.  If the specified command is _XXXX_XXXX______GGGG_EEEE_TTTT_RRRR_EEEE_GGGG_SSSS (line
  76.      9), the driver copies the current device register values to a user data
  77.      area (line 11).  If the user address is invalid, an error code is
  78.      returned.
  79.  
  80.       _1111  _ssss_tttt_rrrr_uuuu_cccc_tttt  _dddd_eeee_vvvv_iiii_cccc_eeee _{{{{                 _////_**** _dddd_eeee_vvvv_iiii_cccc_eeee _rrrr_eeee_gggg_iiii_ssss_tttt_eeee_rrrr_ssss _llll_aaaa_yyyy_oooo_uuuu_tttt _****_////
  81.          _...._...._....
  82.       _2222     _iiii_nnnn_tttt _ssss_tttt_aaaa_tttt_uuuu_ssss_;;;;                   _////_**** _dddd_eeee_vvvv_iiii_cccc_eeee _ssss_tttt_aaaa_tttt_uuuu_ssss _wwww_oooo_rrrr_dddd _****_////
  83.       _3333  _}}}}_;;;;
  84.       _4444  _eeee_xxxx_tttt_eeee_rrrr_nnnn _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_eeee_vvvv_iiii_cccc_eeee _xxxx_xxxx______dddd_eeee_vvvv_[[[[_]]]]_;;;;   _////_**** _pppp_hhhh_yyyy_ssss_iiii_cccc_aaaa_llll _dddd_eeee_vvvv_iiii_cccc_eeee _rrrr_eeee_gggg_iiii_ssss_tttt_eeee_rrrr_ssss _****_////
  85.          _...._...._....
  86.       _5555  _xxxx_xxxx_iiii_oooo_cccc_tttt_llll_((((_dddd_eeee_vvvv______tttt _dddd_eeee_vvvv_,,,, _iiii_nnnn_tttt _cccc_mmmm_dddd_,,,, _vvvv_oooo_iiii_dddd _****_aaaa_rrrr_gggg_,,,, _iiii_nnnn_tttt _mmmm_oooo_dddd_eeee_,,,, _cccc_rrrr_eeee_dddd______tttt _****_cccc_rrrr_pppp_,,,, _iiii_nnnn_tttt _****_rrrr_vvvv_pppp_))))
  87.       _6666  _{{{{
  88.       _7777   _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_eeee_vvvv_iiii_cccc_eeee _****_dddd_pppp_;;;;
  89.       _8888   _ssss_wwww_iiii_tttt_cccc_hhhh _((((_cccc_mmmm_dddd_)))) _{{{{
  90.       _9999   _cccc_aaaa_ssss_eeee _XXXX_XXXX______GGGG_EEEE_TTTT_RRRR_EEEE_GGGG_SSSS_::::       _////_**** _cccc_oooo_pppp_yyyy _dddd_eeee_vvvv_iiii_cccc_eeee _rrrr_eeee_gggg_iiii_ssss_tttt_eeee_rrrr_ssss _tttt_oooo _uuuu_ssss_eeee_rrrr _pppp_rrrr_oooo_gggg_rrrr_aaaa_mmmm _****_////
  91.      _1111_0000        _dddd_pppp _==== _&&&&_xxxx_xxxx______dddd_eeee_vvvv_[[[[_gggg_eeee_tttt_mmmm_iiii_nnnn_oooo_rrrr_((((_dddd_eeee_vvvv_))))_]]]]_;;;;
  92.      _1111_1111        _iiii_ffff _((((_cccc_oooo_pppp_yyyy_oooo_uuuu_tttt_((((_((((_cccc_aaaa_dddd_dddd_rrrr______tttt_))))_dddd_pppp_,,,, _aaaa_rrrr_gggg_,,,, _ssss_iiii_zzzz_eeee_oooo_ffff_((((_ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_eeee_vvvv_iiii_cccc_eeee_))))_))))_))))
  93.      _1111_2222             _rrrr_eeee_tttt_uuuu_rrrr_nnnn _((((_EEEE_FFFF_AAAA_UUUU_LLLL_TTTT_))))_;;;;
  94.      _1111_3333        _bbbb_rrrr_eeee_aaaa_kkkk_;;;;
  95.  
  96. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  97.      _bbbb_cccc_oooo_pppp_yyyy(D3), _cccc_oooo_pppp_yyyy_iiii_nnnn(D3), _uuuu_iiii_oooo_mmmm_oooo_vvvv_eeee(D3), _uuuu_rrrr_eeee_aaaa_dddd_cccc(D3), _uuuu_wwww_rrrr_iiii_tttt_eeee_cccc(D3)
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.                                                                         PPPPaaaaggggeeee 2222
  128.  
  129.  
  130.  
  131.